From 077270142fa196f41d7a86b3c33b0f6ccd83628b Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 21 Nov 2010 21:50:12 -0500 Subject: [PATCH] GtkStyleContext documentation tweaks --- gtk/gtkstylecontext.c | 67 ++++++++++++++++++++++++------------------- 1 file changed, 38 insertions(+), 29 deletions(-) diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c index 3303e74f11..ba65ccdf1c 100644 --- a/gtk/gtkstylecontext.c +++ b/gtk/gtkstylecontext.c @@ -59,7 +59,7 @@ * gtk_style_context_set_path() and gtk_style_context_set_screen(), as well * as updating the context yourself using gtk_style_context_invalidate() * whenever any of the conditions change, such as a change in the - * #GtkSettings:gtk-theme-name property or a hierarchy change in the rendered + * #GtkSettings:gtk-theme-name setting or a hierarchy change in the rendered * widget. * * @@ -67,22 +67,23 @@ * * #GtkStyleContext has built-in support for state change transitions. * - * + * * For simple widgets where state changes affect the whole widget area, - * calling gtk_style_context_notify_state_change() with a %NULL identifier - * would be sufficient. - * + * calling gtk_style_context_notify_state_change() with a %NULL region + * is sufficient. + * * * If a widget needs to declare several animatable regions (i.e. not * affecting the whole widget area), its #GtkWidget::draw signal handler - * needs to wrap the render operations for the different regions around - * gtk_style_context_push_animatable_region() and + * needs to wrap the render operations for the different regions with + * calls to gtk_style_context_push_animatable_region() and * gtk_style_context_pop_animatable_region(). These functions take an - * unique identifier within the style context, for simple widgets with - * little animatable regions, an enum may be used: + * identifier for the region which must be unique within the style context. + * For simple widgets with a fixed set of animatable regions, using an + * enumeration works well: * * - * Using an enum as animatable region identifier + * Using an enumeration to identify animatable regions * * enum { * REGION_ENTRY, @@ -114,11 +115,12 @@ * * * For complex widgets with an arbitrary number of animatable regions, it - * is up to the implementation to come up with a way to univocally identify - * an animatable region, pointers to internal structs would suffice. + * is up to the implementation to come up with a way to uniquely identify + * each animatable region. Using pointers to internal structs is one way + * to achieve this: * * - * Using an arbitrary pointer as animatable region identifier + * Using struct pointers to identify animatable regions * * void * notebook_draw_tab (GtkWidget *widget, @@ -1114,6 +1116,9 @@ gtk_style_context_reset_widgets (GdkScreen *screen) * in style construction for all #GtkStyleContexts under * @screen. * + * GTK+ uses this to make styling information from #GtkSettings + * available. + * * Since: 3.0 **/ void @@ -2468,7 +2473,8 @@ gtk_style_context_lookup_color (GtkStyleContext *context, * * Notifies a state change on @context, so if the current style makes use * of transition animations, one will be started so all rendered elements - * under @region_id are animated for state @state being set to value @state_value. + * under @region_id are animated for state @state being set to value + * @state_value. * * The @window parameter is used in order to invalidate the rendered area * as the animation runs, so make sure it is the same window that is being @@ -2482,23 +2488,24 @@ gtk_style_context_lookup_color (GtkStyleContext *context, * * gtk_style_context_notify_state_change (context, * gtk_widget_get_window (widget), - * NULL, GTK_STATE_PRELIGHT, + * NULL, + * GTK_STATE_PRELIGHT, * button->in_button); * * - * Could be handled in the CSS file like this: + * Can be handled in the CSS file like this: * * GtkButton { - * background-color: #f00; + * background-color: #f00 * } * * GtkButton:hover { - * background-color: #fff; - * transition: 200ms linear; + * background-color: #fff; + * transition: 200ms linear * } * * - * This combination would animate the button background from red to white + * This combination will animate the button background from red to white * if a pointer enters the button, and back to red if the pointer leaves * the button. * @@ -2612,13 +2619,14 @@ gtk_style_context_notify_state_change (GtkStyleContext *context, * @region_id: unique identifier for the animatable region * * Pushes an animatable region, so all further gtk_render_*() calls between - * this call and the following gtk_style_context_pop_animatable_region() will - * potentially show transition animations for if gtk_style_context_notify_state_change() - * is called for a given state, and the theme/style used contemplates the use of - * transition animations for state changes. + * this call and the following gtk_style_context_pop_animatable_region() + * will potentially show transition animations for if + * gtk_style_context_notify_state_change() is called for a given state, + * and the theme/style used contemplates the use of transition animations + * for state changes. * - * The @region_id used must be unique in @context so the theming engine may - * univocally identify rendered elements subject to a state transition. + * The @region_id used must be unique in @context so the theming engine + * can uniquely identify rendered elements subject to a state transition. * * Since: 3.0 **/ @@ -2639,7 +2647,8 @@ gtk_style_context_push_animatable_region (GtkStyleContext *context, * gtk_style_context_pop_animatable_region: * @context: a #GtkStyleContext * - * Pops an animatable region from @context. See gtk_style_context_push_animatable_region(). + * Pops an animatable region from @context. + * See gtk_style_context_push_animatable_region(). * * Since: 3.0 **/ @@ -2715,7 +2724,7 @@ _gtk_style_context_coalesce_animation_areas (GtkStyleContext *context, info->invalidation_region = cairo_region_create (); - for (i = 0; i rectangles->len; i++) + for (i = 0; i < info->rectangles->len; i++) { cairo_rectangle_int_t *rect; @@ -2753,7 +2762,7 @@ store_animation_region (GtkStyleContext *context, info = l->data; - /* The animation doesn't need updatring + /* The animation doesn't need updating * the invalidation area, bail out. */ if (info->invalidation_region) -- 2.30.2